<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<!--

    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

    Copyright (c) 2009-2013 Oracle and/or its affiliates. All rights reserved.

    The contents of this file are subject to the terms of either the GNU
    General Public License Version 2 only ("GPL") or the Common Development
    and Distribution License("CDDL") (collectively, the "License").  You
    may not use this file except in compliance with the License.  You can
    obtain a copy of the License at
    https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    or packager/legal/LICENSE.txt.  See the License for the specific
    language governing permissions and limitations under the License.

    When distributing the software, include this License Header Notice in each
    file and include the License file at packager/legal/LICENSE.txt.

    GPL Classpath Exception:
    Oracle designates this particular file as subject to the "Classpath"
    exception as provided by Oracle in the GPL Version 2 section of the License
    file that accompanied this code.

    Modifications:
    If applicable, add the following below the License Header, with the fields
    enclosed by brackets [] replaced by your own identifying information:
    "Portions Copyright [year] [name of copyright owner]"

    Contributor(s):
    If you wish your version of this file to be governed by only the CDDL or
    only the GPL Version 2, indicate your decision by adding "[Contributor]
    elects to include this software in this distribution under the [CDDL or GPL
    Version 2] license."  If you don't indicate a single choice of license, a
    recipient has the option to distribute your version of this file under
    either the CDDL, the GPL Version 2 or to extend the choice of license to
    its licensees as provided above.  However, if you add GPL Version 2 code
    and therefore, elected the GPL Version 2 license, then the option applies
    only if the new code is made subject to such option by the copyright
    holder.

-->

</HEAD>
<BODY BGCOLOR="white">

<p>Contains annotations and interfaces for defining interceptor methods, interceptor
classes and for binding interceptor classes to target classes.</p>

<h3>Interceptor methods</h3>

<p>An interceptor method may be defined on a target class itself or on an interceptor 
class associated with the target class. {@linkplain javax.interceptor.AroundConstruct} 
interceptor may be defined only on an interceptor class.</p>

<p>There are three kinds of interceptor method:</p>

<ul>
  <li>{@linkplain javax.interceptor.AroundInvoke around-invoke interceptor methods} for 
  business methods of the target class </li>
  <li>{@linkplain javax.interceptor.AroundTimeout around-timeout interceptor methods} 
  for timeout methods of the target class</li>
  <li>lifecycle callback interceptor methods, such as {@link javax.interceptor.AroundConstruct}, 
  {@link javax.annotation.PostConstruct} and {@link javax.annotation.PreDestroy } </li>
</ul>

<p>An interceptor method may be defined using annotations or, optionally, by means of a
deployment descriptor. Interceptor methods may not be declared <tt>static</tt> or 
<tt>final</tt>.</p>

<p>An interceptor class or target class may have multiple interceptor methods. However, 
an interceptor class or target class may have no more than one interceptor method for
a certain type of interception: {@link javax.interceptor.AroundInvoke}, 
{@link javax.interceptor.AroundTimeout}, {@link javax.annotation.PostConstruct}, 
{@link javax.annotation.PreDestroy}, {@link javax.interceptor.AroundConstruct}.</p>

<h3>Interceptor classes</h3>

<p>An interceptor class is a class (distinct from the target class) whose methods are 
invoked in response to invocations and/or lifecycle events on the target class. Any 
number of interceptor classes may be associated with a target class.</p>

<p>An interceptor class must have a public constructor with no parameters.</p>

<p>Interceptor methods and interceptor classes may be defined for a class by means 
of metadata annotations or, optionally, by means of a deployment descriptor.</p>

<h3>Associating an interceptor class with the target class</h3>

<p>An interceptor class may be associated with the target class or a method of the 
target class in several ways:</p>

<ul>
  <li>By annotating both the interceptor class and the target class with an 
  {@linkplain javax.interceptor.InterceptorBinding interceptor binding}. The set of 
  interceptor bindings for the interceptor are specified by annotating the interceptor 
  class with the binding types and the {@link javax.interceptor.Interceptor} 
  annotation.</li>
  <li>By using the {@link javax.interceptor.Interceptors Interceptors} annotation 
  to denote interceptor classes and associate one or more interceptor classes 
  with a target class and/or one or more of its methods.</li>
  <li>If a deployment descriptor is supported, it can be used to associate interceptor 
  classes with the target class and/or methods of the target class and specify the 
  order of interceptor invocation or override metadata specified by annotations.</li>
</ul>

<p>Any interceptor class may be defined to apply to a target class at the class level. 
In the case of around-invoke method interceptors, the interceptor applies to all 
business methods of the target class. In the case of timeout method interceptors, 
the interceptor applies to all timeout methods of the target class.</p>

<p>{@link javax.interceptor.ExcludeClassInterceptors} annotation or, if supported, 
a deployment descriptor may be used to exclude the invocation of class level 
interceptors for a method of a target class.</p>

<p>An around-invoke interceptor may be defined to apply only to a specific method of the 
target class. Likewise, an around-timeout interceptor may be defined to apply only to 
a specific timeout method of the target class. However, if an interceptor class that 
defines lifecycle callback interceptor methods is defined to apply to a target class 
at the method level, the lifecycle callback interceptor methods are not invoked.</p>

<h3>Default Interceptors</h3>

<p>Default interceptors are interceptors that apply to a set of target classes. If a 
deployment descriptor is supported, it may be used to define default interceptors and 
their relative ordering.</p>

<p>{@link javax.interceptor.ExcludeDefaultInterceptors} annotation may be used to 
exclude the invocation of default interceptors for a target class or method of a target class.</p>

<h3>Interceptor lifecycle</h3>

<p>The lifecycle of an interceptor instance is the same as that of the target class 
instance with which it is associated. Except for the {@linkplain javax.interceptor.AroundConstruct}
lifecycle callback interceptors, when the target instance is created, a 
corresponding interceptor instance is created for each associated interceptor class. 
These interceptor instances are destroyed when the target instance fails to be created or
when it is removed.</p>

<p>An interceptor class shares the enterprise naming context of its associated target 
class. Annotations and/or XML deployment descriptor elements for dependency injection or 
for direct JNDI lookup refer to this shared naming context.</p>

<p>An interceptor instance may hold state. An interceptor instance may be the target 
of dependency injection. Dependency injection is performed when the interceptor instance 
is created, using the naming context of the associated target class. With the exception 
of {@linkplain javax.interceptor.AroundConstruct} lifecycle callback interceptors, all 
interceptor methods, including {@linkplain javax.annotation.PostConstruct} interceptor 
callback method are invoked after this dependency injection has taken place on both the 
interceptor instances and the target instance.</p>

<p>{@linkplain javax.annotation.PreDestroy} interceptor callback method, if any, is 
invoked before the target instance and all interceptor instances associated with it are 
destroyed.</p>

<p>When a {@linkplain javax.interceptor.AroundConstruct} lifecycle callback interceptor 
is used, the following rules apply:
<ul>
  <li>The {@linkplain javax.interceptor.AroundConstruct} lifecycle callback is invoked 
  after the dependency injection has been completed on instances of all interceptor 
  classes associated with the target class. Injection of the target component into 
  interceptor instances that are invoked during the {@linkplain javax.interceptor.AroundConstruct} 
  lifecycle callback is not supported.</li>
  <li>The target instance is created and its constructor injection is performed, if applicable, 
  when the last interceptor method in the {@linkplain javax.interceptor.AroundConstruct}
  interceptor chain invokes the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} method. 
  If the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} method is not invoked by an 
  interceptor method, the target instance will not be created.</li>
  <li>The {@linkplain javax.interceptor.AroundConstruct} interceptor method can access 
  the constructed instance using the {@link javax.interceptor.InvocationContext#getTarget InvocationContext.getTarget()}
  method after the {@link javax.interceptor.InvocationContext#proceed InvocationContext.proceed()} completes.</li>
  <li>Dependency injection on the target instance is not completed until after invocation 
  of all interceptor methods in the AroundConstruct interceptor chain complete successfully.
  <li>The {@linkplain javax.annotation.PostConstruct} lifecycle callback chain for the 
  target instance, if any, will be invoked after the dependency injection has been completed 
  on the target instance.</li>
  <li>An {@linkplain javax.interceptor.AroundConstruct} lifecycle callback interceptor 
  method should exercise caution when invoking methods of the target instance since its 
  dependency injection may not have been completed.</li>
</ul>
</p>

<h3>Interceptors for lifecycle callbacks</h3>

<p>A lifecycle callback interceptor method is a non-final, non-static method. A 
lifecycle callback interceptor method declared by the target class (or superclass) must 
have no parameters. A lifecycle callback interceptor method declared by an interceptor 
class must have a single parameter of type {@link javax.interceptor.InvocationContext}.</p>
 
<pre>
&#064;PostConstruct
public void interceptPostConstruct(InvocationContext ctx) { ... }
</pre>

<p>A single lifecycle callback interceptor method may be used to interpose on multiple 
callback events.</p>

<pre>
&#064;PostConstruct &#064;PreDestroy
public void interceptLifecycle(InvocationContext ctx) { ... }
</pre>

<p>A class may not declare more than one lifecycle callback interceptor method for
a particular lifecycle event.</p>
 
<p>Lifecycle callback interceptor methods are invoked in an unspecified security context. 
Lifecycle callback interceptor methods are invoked in a transaction context determined 
by their target class and/or method. The transaction context may be also changed by 
transactional interceptors in the invocation chain.</p>
 
<p>Lifecycle callback interceptor methods may throw runtime exceptions but not checked
exceptions.</p>

@see javax.interceptor.AroundConstruct
@see javax.interceptor.AroundInvoke
@see javax.interceptor.AroundTimeout
@see javax.interceptor.Interceptors
@see javax.interceptor.InvocationContext

</BODY>
</HTML>
